Write The Comments First
「コメントを最初に書く」
開発者の多くは、コーディング終了後にコメントを書こうとする
後から書こうとすると、コメントを書く量が増大し面倒になる
また、設計してから時間が経つと、設計当時の記憶が曖昧になる
コードを見ながらコメントを書くので、コメントはコードと同じこと書きがちに
結果として、コメントに重要な情報が欠けた状態になる
e.g. 新しいクラスを実装する
2. 重要な public メソッドのインタフェースのコメントとシグネチャを書く 実装はまだ記述しない
3. 重要なインタンス変数の宣言とコメントを書く
4. メソッドを実装し、必要に応じてコメントを加える
メソッドやインスタンス変数が追加で必要になるケースもある
メソッド: 同様に、実装の前にインタフェースのコメントとシグネチャを書く
インスタンス変数: 宣言とコメントを書く
実装の過程でコメントに問題があれば、その都度修正する
これにより、コードとコメントが同時に完成する
3つのメリット
良いコメントが書ける
システムの設計を改善できる
コメントを書くのが楽しくなる
良いコメントが書ける
設計中にコメントを書くことで、重要な設計上の問題点を記録するのが簡単になる
また、メソッドの抽象化やインタフェースに注力することができる 実装に気を取られないで済む
システムの設計を改善できる
設計の最初にコメントを書くことで、実装コードを書く前にそのコメントを見直し、調整することで良いコメント（設計）にブラッシュアップできる radish-miyazaki.icon
良いコメント = 抽象化を上手く説明している radish-miyazaki.icon
良いコメントを書くためには、変数やコードの本質を見極める必要がある
設計の最初にこれを行うことで、その場しのぎのコードを記述しなくて済む radish-miyazaki.icon
メソッドや変数に長いコメントが必要 = 抽象化がうまくできていない 強力な機能を提供しながらも、シンプルなインタフェースを持つ radish-miyazaki.icon
コメントはインタフェースがシンプルかどうかの判断材料となる
コメントが必要な情報を提供しつつ、短くてシンプル = インタフェースもシンプル
逆に、コメントが長くて複雑である = インタフェースも複雑
インタフェースのコメントと実装を比較することで、そのモジュールが深いかどうかも判断可能
インタフェースコメントが実装の主要な機能をすべて説明する必要がある = 浅い
ただし、判断できるのはコメントが明白である場合に限り、以下のようなケースは判断できない
e.g. コメントが必要な情報を提供していないケース
e.g. コメントが理解が難しいほど不可解ケース
コメントを先に書くことで、「抽象化がうまくできていない」という問題に早い段階で気づくことができる コメントを書くのが楽しくなる
コメントは、設計時の決定を記録し、チェックするためのもの
どれだけコメントをシンプルに書くか = 設計がシンプルか 設計力の判断材料となり、モチベーションにも
「先にコメントを書くこと」のコストは低い
全コード行の半分がコメントであったとしても、コメントを書く時間は全開発時間の 5% にも満たない
コメントを書くのを後回しにしても、節約できる時間はたかが知れている
最初にコメントを書くと、コードを書き始める前に 抽象化 がより安定したものになる 結果として、コーディング時間の節約につながる
逆にコードを先に書くと、抽象化された部分は後から変更される可能性が高いので、より多くのコードの修正が必要となる